Summary

This PR adds response model classes for the document search API, enabling a clean and intuitive interface for working with search results.

• Document class: Represents a document returned from search with id, score, and dynamic field access
• DocumentSearchResponse class: Wraps the list of documents with usage information

Problem

The document search API needs response models that allow users to easily access search results. Documents can have dynamic fields (varying per index schema), so the Document class needs to support flexible field access patterns.

Solution

The Document class provides three ways to access fields:

# Attribute access
doc.title  # "The Pink Panther"

# Dict-style access
doc["title"]  # "The Pink Panther"

# Safe get with default
doc.get("title", "N/A")  # "The Pink Panther"
doc.get("missing", "Unknown")  # "Unknown"

The class also supports:

• Standard id and score properties
• keys(), values(), items() for iteration
• in operator for field existence checks
• to_dict() for serialization
• Equality comparison

Usage Example

from pinecone import Pinecone, text_query

pc = Pinecone()
index = pc.Index("movies")

results = index.search_documents(
    namespace="movies",
    score_by=text_query("title", "pink panther"),
    top_k=10,
)

for doc in results.documents:
    print(f"{doc.id}: {doc.score}")
    print(f"  Title: {doc.title}")
    print(f"  Year: {doc.get('year', 'Unknown')}")

Test Plan

• Unit tests for attribute access to dynamic fields
• Unit tests for dict-style access (doc["field"])
• Unit tests for safe get() with default values
• Unit tests for DocumentSearchResponse wrapper
• Unit tests for edge cases (missing fields, equality, repr)
• mypy type checking passes
• All 31 new tests pass

Related

• Linear: SDK-110
• Depends on: PR#11 (Query factory functions - text_query, vector_query)